！ 本篇文章將會介紹 /init 與 AGENTS.md，這是 opencode 讀懂你專案的第一步，五秒鐘讓 AI 少猜一半 :D

TL;DR: https://dev.benben.me/slides/s/ironman-04-init-agents-md

本篇目標

讀完這篇你會學到：

• 會用 /init 生成專案的 AGENTS.md
• 知道 AGENTS.md 該寫什麼、放在哪、給誰看
• 建立「專案說明書」的維護習慣

為什麼需要 AGENTS.md？

想像今天報到一位新人 engineer，你會怎麼帶？多半是丟一份 onboarding 文件給他：「我們專案長這樣、測試這樣跑、code 要照這個慣例寫」。

AI 也一樣。沒有說明書的 AI，就像沒看 onboarding 文件就上手改 code 的新人——亂猜一通，改出來的東西不符合團隊慣例，你還得花時間 review 修回去。

AGENTS.md 就是給 AI 的 onboarding 文件：放在專案根目錄，內容會自動加進 LLM 的 context，客製它在「你這個專案」的行為。

另外 Claude Code 的 AGENTS.md 就叫 CLAUDE.md，呃，對就他最特別，沒辨法因為他是 Anthropic，Shoppify 的 CEO 甚至為了這個揚言要 ban Claude Code。

延伸閱讀：Shoppify 的 CEO Tobi 的 X https://x.com/tobi/status/2092259436538495186。

/init：五秒鐘的自動 onboarding

在 opencode 裡輸入：

/init

它會掃描 repo 裡的重要檔案，必要時問你幾個問題（codebase 答不出來的，就由你來補答），然後生成或更新 AGENTS.md。

/init 會專注在「未來的 agent session 最需要知道的事」：

• build / lint / test 指令（跟順序）
• 從檔名看不出來的架構與 repo 結構
• 專案特有的慣例、設定地雷、注意事項
• 既有的指示來源（例如 Cursor rules、Copilot 設定）

還有個貼心細節：如果你已經有 AGENTS.md，/init 會在原地改良它，不是盲蓋掉。你手動補充的內容不會無辜消失。

AGENTS.md 該寫什麼？

來一個精簡的範例感受一下：

# SST v3 Monorepo Project

TypeScript 專案，用 bun workspaces 管套件。

## Project Structure

- `packages/` - 所有 workspace packages（functions、core、web）
- `infra/` - 基礎設施定義，按服務拆檔
- `sst.config.ts` - SST 主設定

## Code Standards

- TypeScript strict mode
- 共用程式碼放 `packages/core/`
- import 共用模組用 workspace 名稱：`@my-app/core/example`

口訣就四類：專案簡介、目錄結構、coding 慣例、常用指令。寫你 onboarding 新人會講的話就對了。

兩個層級：專案的事 vs 個人的事

AGENTS.md 有兩個存放位置，分工清楚：

個人的慣例（例如「回覆用繁中」）放全域；團隊的規範（例如「commit 前必跑測試」）放專案。這樣換專案不用重寫，帶新人直接 clone 就有道可循。

寫一次，到處用

AGENTS.md 是跨工具的公開慣例，不只 opencode 用。opencode 還會自動相容 Claude Code 的慣例：專案沒有 AGENTS.md 時會退回讀 CLAUDE.md，全域也支援 ~/.claude/CLAUDE.md。

小小測驗：如果專案裡 AGENTS.md 和 CLAUDE.md 同時存在，你猜 opencode 會讀哪一個？
答案：AGENTS.md 優先。CLAUDE.md 只是找不到 AGENTS.md 時的備案，然後，對，你知道的目前 Claude Code 不會讀 AGENTS.md。

常見問題 / 踩坑記錄

• Q：AGENTS.md 生成完就放著長灰塵嗎？
  A：不行，它是活文件。專案慣例變了、加了新指令，就回去更新（通常會自己更新，或是再跑一次 /init 也行）。過時的說明書比沒有更可怕。
• Q：我有多個專案共用一套慣例怎麼辦？
  A：共通的寫進全域 AGENTS.md，差異留在各專案。更進階的玩法（引用外部文件）Day 12 會講。

小結

• /init 沒下過的專案先下，AI 少就猜一半
• AGENTS.md = 給 AI 的 onboarding 文件，四類內容：簡介、結構、慣例、指令
• 專案層給團隊、全域層給自己，commit 進 git 讓全隊升級

明日預告

Day 05：Plan mode vs Build mode——學會先規劃再動手，像帶 junior 一樣跟 AI 對齊認知。

參考資料：

• Rules | opencode docs

有任何疑問但沒有 iT 邦幫忙帳號，或是想匿名提問？
歡迎到 https://dev.benben.me/q/P3C5U6 提問或加油打氣，沒意外的話會在完賽之後一起回答 :D